home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 1998 November
/
Freeware November 1998.img
/
dist
/
fw_elisp-manual-19.idb
/
usr
/
freeware
/
info
/
elisp-25.z
/
elisp-25
(
.txt
)
Wrap
GNU Info File
|
1998-05-26
|
50KB
|
933 lines
This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual. It corresponds to Emacs Version 19.34.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp, Node: Character Motion, Next: Word Motion, Up: Motion
Motion by Characters
--------------------
These functions move point based on a count of characters.
`goto-char' is the fundamental primitive; the other functions use that.
- Command: goto-char POSITION
This function sets point in the current buffer to the value
POSITION. If POSITION is less than 1, it moves point to the
beginning of the buffer. If POSITION is greater than the length
of the buffer, it moves point to the end.
If narrowing is in effect, POSITION still counts from the
beginning of the buffer, but point cannot go outside the accessible
portion. If POSITION is out of range, `goto-char' moves point to
the beginning or the end of the accessible portion.
When this function is called interactively, POSITION is the
numeric prefix argument, if provided; otherwise it is read from the
minibuffer.
`goto-char' returns POSITION.
- Command: forward-char &optional COUNT
This function moves point COUNT characters forward, towards the
end of the buffer (or backward, towards the beginning of the
buffer, if COUNT is negative). If the function attempts to move
point past the beginning or end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), an error is
signaled with error code `beginning-of-buffer' or `end-of-buffer'.
In an interactive call, COUNT is the numeric prefix argument.
- Command: backward-char &optional COUNT
This function moves point COUNT characters backward, towards the
beginning of the buffer (or forward, towards the end of the
buffer, if COUNT is negative). If the function attempts to move
point past the beginning or end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), an error is
signaled with error code `beginning-of-buffer' or `end-of-buffer'.
In an interactive call, COUNT is the numeric prefix argument.
File: elisp, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
Motion by Words
---------------
These functions for parsing words use the syntax table to decide
whether a given character is part of a word. *Note Syntax Tables::.
- Command: forward-word COUNT
This function moves point forward COUNT words (or backward if
COUNT is negative). Normally it returns `t'. If this motion
encounters the beginning or end of the buffer, or the limits of the
accessible portion when narrowing is in effect, point stops there
and the value is `nil'.
In an interactive call, COUNT is set to the numeric prefix
argument.
- Command: backward-word COUNT
This function is just like `forward-word', except that it moves
backward until encountering the front of a word, rather than
forward.
In an interactive call, COUNT is set to the numeric prefix
argument.
This function is rarely used in programs, as it is more efficient
to call `forward-word' with a negative argument.
- Variable: words-include-escapes
This variable affects the behavior of `forward-word' and everything
that uses it. If it is non-`nil', then characters in the "escape"
and "character quote" syntax classes count as part of words.
Otherwise, they do not.
File: elisp, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
Motion to an End of the Buffer
------------------------------
To move point to the beginning of the buffer, write:
(goto-char (point-min))
Likewise, to move to the end of the buffer, use:
(goto-char (point-max))
Here are two commands that users use to do these things. They are
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.
- Command: beginning-of-buffer &optional N
This function moves point to the beginning of the buffer (or the
limits of the accessible portion, when narrowing is in effect),
setting the mark at the previous position. If N is non-`nil',
then it puts point N tenths of the way from the beginning of the
buffer.
In an interactive call, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this function in Lisp programs!
- Command: end-of-buffer &optional N
This function moves point to the end of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting
the mark at the previous position. If N is non-`nil', then it puts
point N tenths of the way from the end of the buffer.
In an interactive call, N is the numeric prefix argument, if
provided; otherwise N defaults to `nil'.
Don't use this function in Lisp programs!
File: elisp, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
Motion by Text Lines
--------------------
Text lines are portions of the buffer delimited by newline
characters, which are regarded as part of the previous line. The first
text line begins at the beginning of the buffer, and the last text line
ends at the end of the buffer whether or not the last character is a
newline. The division of the buffer into text lines is not affected by
the width of the window, by line continuation in display, or by how
tabs and control characters are displayed.
- Command: goto-line LINE
This function moves point to the front of the LINEth line,
counting from line 1 at beginning of the buffer. If LINE is less
than 1, it moves point to the beginning of the buffer. If LINE is
greater than the number of lines in the buffer, it moves point to
the end of the buffer--that is, the *end of the last line* of the
buffer. This is the only case in which `goto-line' does not
necessarily move to the beginning of a line.
If narrowing is in effect, then LINE still counts from the
beginning of the buffer, but point cannot go outside the accessible
portion. So `goto-line' moves point to the beginning or end of the
accessible portion, if the line number specifies an inaccessible
position.
The return value of `goto-line' is the difference between LINE and
the line number of the line to which point actually was able to
move (in the full buffer, before taking account of narrowing).
Thus, the value is positive if the scan encounters the real end of
the buffer. The value is zero if scan encounters the end of the
accessible portion but not the real end of the buffer.
In an interactive call, LINE is the numeric prefix argument if one
has been provided. Otherwise LINE is read in the minibuffer.
- Command: beginning-of-line &optional COUNT
This function moves point to the beginning of the current line.
With an argument COUNT not `nil' or 1, it moves forward COUNT-1
lines and then to the beginning of the line.
If this function reaches the end of the buffer (or of the
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- Command: end-of-line &optional COUNT
This function moves point to the end of the current line. With an
argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
then to the end of the line.
If this function reaches the end of the buffer (or of the
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- Command: forward-line &optional COUNT
This function moves point forward COUNT lines, to the beginning of
the line. If COUNT is negative, it moves point -COUNT lines
backward, to the beginning of a line. If COUNT is zero, it moves
point to the beginning of the current line.
If `forward-line' encounters the beginning or end of the buffer (or
of the accessible portion) before finding that many lines, it sets
point there. No error is signaled.
`forward-line' returns the difference between COUNT and the number
of lines actually moved. If you attempt to move down five lines
from the beginning of a buffer that has only three lines, point
stops at the end of the last line, and the value will be 2.
In an interactive call, COUNT is the numeric prefix argument.
- Function: count-lines START END
This function returns the number of lines between the positions
START and END in the current buffer. If START and END are equal,
then it returns 0. Otherwise it returns at least 1, even if START
and END are on the same line. This is because the text between
them, considered in isolation, must contain at least one line
unless it is empty.
Here is an example of using `count-lines':
(defun current-line ()
"Return the vertical position of point..."
(+ (count-lines (window-start) (point))
(if (= (current-column) 0) 1 0)
-1))
Also see the functions `bolp' and `eolp' in *Note Near Point::.
These functions do not move point, but test whether it is already at the
beginning or end of a line.
File: elisp, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
Motion by Screen Lines
----------------------
The line functions in the previous section count text lines,
delimited only by newline characters. By contrast, these functions
count screen lines, which are defined by the way the text appears on
the screen. A text line is a single screen line if it is short enough
to fit the width of the selected window, but otherwise it may occupy
several screen lines.
In some cases, text lines are truncated on the screen rather than
continued onto additional screen lines. In these cases,
`vertical-motion' moves point much like `forward-line'. *Note
Truncation::.
Because the width of a given string depends on the flags that control
the appearance of certain characters, `vertical-motion' behaves
differently, for a given piece of text, depending on the buffer it is
in, and even on the selected window (because the width, the truncation
flag, and display table may vary between windows). *Note Usual
Display::.
These functions scan text to determine where screen lines break, and
thus take time proportional to the distance scanned. If you intend to
use them heavily, Emacs provides caches which may improve the
performance of your code. *Note cache-long-line-scans: Text Lines.
- Function: vertical-motion COUNT &optional WINDOW
This function moves point to the start of the screen line COUNT
screen lines down from the screen line containing point. If COUNT
is negative, it moves up instead.
`vertical-motion' returns the number of lines moved. The value may
be less in absolute value than COUNT if the beginning or end of
the buffer was reached.
The window WINDOW is used for obtaining parameters such as the
width, the horizontal scrolling, and the display table. But
`vertical-motion' always operates on the current buffer, even if
WINDOW currently displays some other buffer.
- Command: move-to-window-line COUNT
This function moves point with respect to the text currently
displayed in the selected window. It moves point to the beginning
of the screen line COUNT screen lines from the top of the window.
If COUNT is negative, that specifies a position -COUNT lines from
the bottom (or the last line of the buffer, if the buffer ends
above the specified screen position).
If COUNT is `nil', then point moves to the beginning of the line
in the middle of the window. If the absolute value of COUNT is
greater than the size of the window, then point moves to the place
that would appear on that screen line if the window were tall
enough. This will probably cause the next redisplay to scroll to
bring that location onto the screen.
In an interactive call, COUNT is the numeric prefix argument.
The value returned is the window line number point has moved to,
with the top line in the window numbered 0.
- Function: compute-motion FROM FROMPOS TO TOPOS WIDTH OFFSETS WINDOW
This function scans the current buffer, calculating screen
positions. It scans the buffer forward from position FROM,
assuming that is at screen coordinates FROMPOS, to position TO or
coordinates TOPOS, whichever comes first. It returns the ending
buffer position and screen coordinates.
The coordinate arguments FROMPOS and TOPOS are cons cells of the
form `(HPOS . VPOS)'.
The argument WIDTH is the number of columns available to display
text; this affects handling of continuation lines. Use the value
returned by `window-width' for the window of your choice;
normally, use `(window-width WINDOW)'.
The argument OFFSETS is either `nil' or a cons cell of the form
`(HSCROLL . TAB-OFFSET)'. Here HSCROLL is the number of columns
not being displayed at the left margin; most callers get this from
`window-hscroll'. Meanwhile, TAB-OFFSET is the offset between
column numbers on the screen and column numbers in the buffer.
This can be nonzero in a continuation line, when the previous
screen lines' widths do not add up to a multiple of `tab-width'.
It is always zero in a non-continuation line.
The window WINDOW serves only to specify which display table to
use. `compute-motion' always operates on the current buffer,
regardless of what buffer is displayed in WINDOW.
The return value is a list of five elements:
(POS VPOS HPOS PREVHPOS CONTIN)
Here POS is the buffer position where the scan stopped, VPOS is
the vertical screen position, and HPOS is the horizontal screen
position.
The result PREVHPOS is the horizontal position one character back
from POS. The result CONTIN is `t' if the last line was continued
after (or within) the previous character.
For example, to find the buffer position of column COL of line
LINE of a certain window, pass the window's display start location
as FROM and the window's upper-left coordinates as FROMPOS. Pass
the buffer's `(point-max)' as TO, to limit the scan to the end of
the accessible portion of the buffer, and pass LINE and COL as
TOPOS. Here's a function that does this:
(defun coordinates-of-position (col line)
(car (compute-motion (window-start)
'(0 . 0)
(point-max)
(cons col line)
(window-width)
(cons (window-hscroll) 0)
(selected-window))))
When you use `compute-motion' for the minibuffer, you need to use
`minibuffer-prompt-width' to get the horizontal position of the
beginning of the first screen line. *Note Minibuffer Misc::.
File: elisp, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
Moving over Balanced Expressions
--------------------------------
Here are several functions concerned with balanced-parenthesis
expressions (also called "sexps" in connection with moving across them
in Emacs). The syntax table controls how these functions interpret
various characters; see *Note Syntax Tables::. *Note Parsing
Expressions::, for lower-level primitives for scanning sexps or parts of
sexps. For user-level commands, see *Note Lists Commands: (emacs)Lists
Commands.
- Command: forward-list ARG
This function moves forward across ARG balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.)
- Command: backward-list ARG
This function moves backward across ARG balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.)
- Command: up-list ARG
This function moves forward out of ARG levels of parentheses. A
negative argument means move backward but still to a less deep
spot.
- Command: down-list ARG
This function moves forward into ARG levels of parentheses. A
negative argument means move backward but still go deeper in
parentheses (-ARG levels).
- Command: forward-sexp ARG
This function moves forward across ARG balanced expressions.
Balanced expressions include both those delimited by parentheses
and other kinds, such as words and string constants. For example,
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------
(forward-sexp 3)
=> nil
---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
- Command: backward-sexp ARG
This function moves backward across ARG balanced expressions.
- Command: beginning-of-defun ARG
This function moves back to the ARGth beginning of a defun. If
ARG is negative, this actually moves forward, but it still moves
to the beginning of a defun, not to the end of one.
- Command: end-of-defun ARG
This function moves forward to the ARGth end of a defun. If ARG
is negative, this actually moves backward, but it still moves to
the end of a defun, not to the beginning of one.
- User Option: defun-prompt-regexp
If non-`nil', this variable holds a regular expression that
specifies what text can appear before the open-parenthesis that
starts a defun. That is to say, a defun begins on a line that
starts with a match for this regular expression, followed by a
character with open-parenthesis syntax.
File: elisp, Node: Skipping Characters, Prev: List Motion, Up: Motion
Skipping Characters
-------------------
The following two functions move point over a specified set of
characters. For example, they are often used to skip whitespace. For
related functions, see *Note Motion and Syntax::.
- Function: skip-chars-forward CHARACTER-SET &optional LIMIT
This function moves point in the current buffer forward, skipping
over a given set of characters. It examines the character
following point, then advances point if the character matches
CHARACTER-SET. This continues until it reaches a character that
does not match. The function returns `nil'.
The argument CHARACTER-SET is like the inside of a `[...]' in a
regular expression except that `]' is never special and `\' quotes
`^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
stopping before the first nonletter, and `"^a-zA-Z"' skips
nonletters stopping before the first letter. *Note Regular
Expressions::.
If LIMIT is supplied (it must be a number or a marker), it
specifies the maximum position in the buffer that point can be
skipped to. Point will stop at or before LIMIT.
In the following example, point is initially located directly
before the `T'. After the form is evaluated, point is located at
the end of that line (between the `t' of `hat' and the newline).
The function skips all letters and spaces, but not newlines.
---------- Buffer: foo ----------
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
(skip-chars-forward "a-zA-Z ")
=> nil
---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
- Function: skip-chars-backward CHARACTER-SET &optional LIMIT
This function moves point backward, skipping characters that match
CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
except for the direction of motion.
File: elisp, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
Excursions
==========
It is often useful to move point "temporarily" within a localized
portion of the program, or to switch buffers temporarily. This is
called an "excursion", and it is done with the `save-excursion' special
form. This construct saves the current buffer and its values of point
and the mark so they can be restored after the completion of the
excursion.
The forms for saving and restoring the configuration of windows are
described elsewhere (see *Note Window Configurations::, and *note Frame
Configurations::.).
- Special Form: save-excursion FORMS...
The `save-excursion' special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
FORMS, and finally restores the buffer and its saved values of
point and the mark. All three saved values are restored even in
case of an abnormal exit via `throw' or error (*note Nonlocal
Exits::.).
The `save-excursion' special form is the standard way to switch
buffers or move point within one part of a program and avoid
affecting the rest of the program. It is used more than 500 times
in the Lisp sources of Emacs.
`save-excursion' does not save the values of point and the mark for
other buffers, so changes in other buffers remain in effect after
`save-excursion' exits.
Likewise, `save-excursion' does not restore window-buffer
correspondences altered by functions such as `switch-to-buffer'.
One way to restore these correspondences, and the selected window,
is to use `save-window-excursion' inside `save-excursion' (*note
Window Configurations::.).
The value returned by `save-excursion' is the result of the last of
FORMS, or `nil' if no FORMS are given.
(save-excursion
FORMS)
==
(let ((old-buf (current-buffer))
(old-pnt (point-marker))
(old-mark (copy-marker (mark-marker))))
(unwind-protect
(progn FORMS)
(set-buffer old-buf)
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
File: elisp, Node: Narrowing, Prev: Excursions, Up: Positions
Narrowing
=========
"Narrowing" means limiting the text addressable by Emacs editing
commands to a limited range of characters in a buffer. The text that
remains addressable is called the "accessible portion" of the buffer.
Narrowing is specified with two buffer positions which become the
beginning and end of the accessible portion. For most editing commands
and most Emacs primitives, these positions replace the values of the
beginning and end of the buffer. While narrowing is in effect, no text
outside the accessible portion is displayed, and point cannot move
outside the accessible portion.
Values such as positions or line numbers, which usually count from
the beginning of the buffer, do so despite narrowing, but the functions
which use them refuse to operate on text that is inaccessible.
The commands for saving buffers are unaffected by narrowing; they
save the entire buffer regardless of any narrowing.
- Command: narrow-to-region START END
This function sets the accessible portion of the current buffer to
start at START and end at END. Both arguments should be character
positions.
In an interactive call, START and END are set to the bounds of the
current region (point and the mark, with the smallest first).
- Command: narrow-to-page MOVE-COUNT
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
MOVE-COUNT non-`nil' means to move forward or backward by
MOVE-COUNT pages and then narrow. The variable `page-delimiter'
specifies where pages start and end (*note Standard Regexps::.).
In an interactive call, MOVE-COUNT is set to the numeric prefix
argument.
- Command: widen
This function cancels any narrowing in the current buffer, so that
the entire contents are accessible. This is called "widening".
It is equivalent to the following expression:
(narrow-to-region 1 (1+ (buffer-size)))
- Special Form: save-restriction BODY...
This special form saves the current bounds of the accessible
portion, evaluates the BODY forms, and finally restores the saved
bounds, thus restoring the same state of narrowing (or absence
thereof) formerly in effect. The state of narrowing is restored
even in the event of an abnormal exit via `throw' or error (*note
Nonlocal Exits::.). Therefore, this construct is a clean way to
narrow a buffer temporarily.
The value returned by `save-restriction' is that returned by the
last form in BODY, or `nil' if no body forms were given.
*Caution:* it is easy to make a mistake when using the
`save-restriction' construct. Read the entire description here
before you try it.
If BODY changes the current buffer, `save-restriction' still
restores the restrictions on the original buffer (the buffer whose
restructions it saved from), but it does not restore the identity
of the current buffer.
`save-restriction' does *not* restore point and the mark; use
`save-excursion' for that. If you use both `save-restriction' and
`save-excursion' together, `save-excursion' should come first (on
the outside). Otherwise, the old point value would be restored
with temporary narrowing still in effect. If the old point value
were outside the limits of the temporary narrowing, this would
fail to restore it accurately.
The `save-restriction' special form records the values of the
beginning and end of the accessible portion as distances from the
beginning and end of the buffer. In other words, it records the
amount of inaccessible text before and after the accessible
portion.
This method yields correct results if BODY does further narrowing.
However, `save-restriction' can become confused if the body widens
and then make changes outside the range of the saved narrowing.
When this is what you want to do, `save-restriction' is not the
right tool for the job. Here is what you must use instead:
(let ((beg (point-min-marker))
(end (point-max-marker)))
(unwind-protect
(progn BODY)
(save-excursion
(set-buffer (marker-buffer beg))
(narrow-to-region beg end))))
Here is a simple example of correct use of `save-restriction':
---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo-!-
---------- Buffer: foo ----------
(save-excursion
(save-restriction
(goto-char 1)
(forward-line 2)
(narrow-to-region 1 (point))
(goto-char (point-min))
(replace-string "foo" "bar")))
---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo-!-
---------- Buffer: foo ----------
File: elisp, Node: Markers, Next: Text, Prev: Positions, Up: Top
Markers
*******
A "marker" is a Lisp object used to specify a position in a buffer
relative to the surrounding text. A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.
* Menu:
* Overview of Markers:: The components of a marker, and how it relocates.
* Predicates on Markers:: Testing whether an object is a marker.
* Creating Markers:: Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers:: Moving the marker to a new buffer or position.
* The Mark:: How "the mark" is implemented with a marker.
* The Region:: How to access "the region".
File: elisp, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
Overview of Markers
===================
A marker specifies a buffer and a position in that buffer. The
marker can be used to represent a position in the functions that
require one, just as an integer could be used. *Note Positions::, for
a complete description of positions.
A marker has two attributes: the marker position, and the marker
buffer. The marker position is an integer that is equivalent (at a
given time) to the marker as a position in that buffer. But the
marker's position value can change often during the life of the marker.
Insertion and deletion of text in the buffer relocate the marker. The
idea is that a marker positioned between two characters remains between
those two characters despite insertion and deletion elsewhere in the
buffer. Relocation changes the integer equivalent of the marker.
Deleting text around a marker's position leaves the marker between
the characters immediately before and after the deleted text. Inserting
text at the position of a marker normally leaves the marker in front of
the new text--unless it is inserted with `insert-before-markers' (*note
Insertion::.).
Insertion and deletion in a buffer must check all the markers and
relocate them if necessary. This slows processing in a buffer with a
large number of markers. For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
Unreferenced markers are garbage collected eventually, but until then
will continue to use time if they do point somewhere.
Because it is common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including `+' and `-')
accept markers as arguments. In such cases, the marker stands for its
current position.
Here are examples of creating markers, setting markers, and moving
point to markers:
;; Make a new marker that initially does not point anywhere:
(setq m1 (make-marker))
=> #<marker in no buffer>
;; Set `m1' to point between the 99th and 100th characters
;; in the current buffer:
(set-marker m1 100)
=> #<marker at 100 in markers.texi>
;; Now insert one character at the beginning of the buffer:
(goto-char (point-min))
=> 1
(insert "Q")
=> nil
;; `m1' is updated appropriately.
m1
=> #<marker at 101 in markers.texi>
;; Two markers that point to the same position
;; are not `eq', but they are `equal'.
(setq m2 (copy-marker m1))
=> #<marker at 101 in markers.texi>
(eq m1 m2)
=> nil
(equal m1 m2)
=> t
;; When you are finished using a marker, make it point nowhere.
(set-marker m1 nil)
=> #<marker in no buffer>
File: elisp, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
Predicates on Markers
=====================
You can test an object to see whether it is a marker, or whether it
is either an integer or a marker. The latter test is useful in
connection with the arithmetic functions that work with both markers
and integers.
- Function: markerp OBJECT
This function returns `t' if OBJECT is a marker, `nil' otherwise.
Note that integers are not markers, even though many functions
will accept either a marker or an integer.
- Function: integer-or-marker-p OBJECT
This function returns `t' if OBJECT is an integer or a marker,
`nil' otherwise.
- Function: number-or-marker-p OBJECT
This function returns `t' if OBJECT is a number (either kind) or a
marker, `nil' otherwise.
File: elisp, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
Functions That Create Markers
=============================
When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.
- Function: make-marker
This functions returns a newly created marker that does not point
anywhere.
(make-marker)
=> #<marker in no buffer>
- Function: point-marker
This function returns a new marker that points to the present
position of point in the current buffer. *Note Point::. For an
example, see `copy-marker', below.
- Function: point-min-marker
This function returns a new marker that points to the beginning of
the accessible portion of the buffer. This will be the beginning
of the buffer unless narrowing is in effect. *Note Narrowing::.
- Function: point-max-marker
This function returns a new marker that points to the end of the
accessible portion of the buffer. This will be the end of the
buffer unless narrowing is in effect. *Note Narrowing::.
Here are examples of this function and `point-min-marker', shown in
a buffer containing a version of the source file for the text of
this chapter.
(point-min-marker)
=> #<marker at 1 in markers.texi>
(point-max-marker)
=> #<marker at 15573 in markers.texi>
(narrow-to-region 100 200)
=> nil
(point-min-marker)
=> #<marker at 100 in markers.texi>
(point-max-marker)
=> #<marker at 200 in markers.texi>
- Function: copy-marker MARKER-OR-INTEGER
If passed a marker as its argument, `copy-marker' returns a new
marker that points to the same place and the same buffer as does
MARKER-OR-INTEGER. If passed an integer as its argument,
`copy-marker' returns a new marker that points to position
MARKER-OR-INTEGER in the current buffer.
If passed an integer argument less than 1, `copy-marker' returns a
new marker that points to the beginning of the current buffer. If
passed an integer argument greater than the length of the buffer,
`copy-marker' returns a new marker that points to the end of the
buffer.
An error is signaled if MARKER is neither a marker nor an integer.
(setq p (point-marker))
=> #<marker at 2139 in markers.texi>
(setq q (copy-marker p))
=> #<marker at 2139 in markers.texi>
(eq p q)
=> nil
(equal p q)
=> t
(copy-marker 0)
=> #<marker at 1 in markers.texi>
(copy-marker 20000)
=> #<marker at 7572 in markers.texi>
File: elisp, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
Information from Markers
========================
This section describes the functions for accessing the components of
a marker object.
- Function: marker-position MARKER
This function returns the position that MARKER points to, or `nil'
if it points nowhere.
- Function: marker-buffer MARKER
This function returns the buffer that MARKER points into, or `nil'
if it points nowhere.
(setq m (make-marker))
=> #<marker in no buffer>
(marker-position m)
=> nil
(marker-buffer m)
=> nil
(set-marker m 3770 (current-buffer))
=> #<marker at 3770 in markers.texi>
(marker-buffer m)
=> #<buffer markers.texi>
(marker-position m)
=> 3770
Two distinct markers are considered `equal' (even though not `eq')
to each other if they have the same position and buffer, or if they
both point nowhere.
File: elisp, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
Changing Marker Positions
=========================
This section describes how to change the position of an existing
marker. When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it--otherwise, confusing things may happen in other parts of
Emacs.
- Function: set-marker MARKER POSITION &optional BUFFER
This function moves MARKER to POSITION in BUFFER. If BUFFER is
not provided, it defaults to the current buffer.
If POSITION is less than 1, `set-marker' moves MARKER to the
beginning of the buffer. If POSITION is greater than the size of
the buffer, `set-marker' moves marker to the end of the buffer.
If POSITION is `nil' or a marker that points nowhere, then MARKER
is set to point nowhere.
The value returned is MARKER.
(setq m (point-marker))
=> #<marker at 4714 in markers.texi>
(set-marker m 55)
=> #<marker at 55 in markers.texi>
(setq b (get-buffer "foo"))
=> #<buffer foo>
(set-marker m 0 b)
=> #<marker at 1 in foo>
- Function: move-marker MARKER POSITION &optional BUFFER
This is another name for `set-marker'.
File: elisp, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
The Mark
========
One special marker in each buffer is designated "the mark". It
records a position for the user for the sake of commands such as `C-w'
and `C-x TAB'. Lisp programs should set the mark only to values that
have a potential use to the user, and never for their own internal
purposes. For example, the `replace-regexp' command sets the mark to
the value of point before doing any replacements, because this enables
the user to move back there conveniently after the replace is finished.
Many commands are designed so that when called interactively they
operate on the text between point and the mark. If you are writing such
a command, don't examine the mark directly; instead, use `interactive'
with the `r' specification. This provides the values of point and the
mark as arguments to the command in an interactive call, but permits
other Lisp programs to specify arguments explicitly. *Note Interactive
Codes::.
Each buffer has its own value of the mark that is independent of the
value of the mark in other buffers. When a buffer is created, the mark
exists but does not point anywhere. We consider this state as "the
absence of a mark in that buffer."
Once the mark "exists" in a buffer, it normally never ceases to
exist. However, it may become "inactive", if Transient Mark mode is
enabled. The variable `mark-active', which is always local in all
buffers, indicates whether the mark is active: non-`nil' means yes. A
command can request deactivation of the mark upon return to the editor
command loop by setting `deactivate-mark' to a non-`nil' value (but
this causes deactivation only if Transient Mark mode is enabled).
The main motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active. *Note
Display::.
In addition to the mark, each buffer has a "mark ring" which is a
list of markers containing previous values of the mark. When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring. The variable `mark-ring-max' specifies the
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.
- Function: mark &optional FORCE
This function returns the current buffer's mark position as an
integer.
If the mark is inactive, `mark' normally signals an error.
However, if FORCE is non-`nil', then `mark' returns the mark
position anyway--or `nil', if the mark is not yet set for this
buffer.
- Function: mark-marker
This function returns the current buffer's mark. This is the very
marker that records the mark location inside Emacs, not a copy.
Therefore, changing this marker's position will directly affect
the position of the mark. Don't do it unless that is the effect
you want.
(setq m (mark-marker))
=> #<marker at 3420 in markers.texi>
(set-marker m 100)
=> #<marker at 100 in markers.texi>
(mark-marker)
=> #<marker at 100 in markers.texi>
Like any marker, this marker can be set to point at any buffer you
like. We don't recommend that you make it point at any buffer
other than the one of which it is the mark. If you do, it will
yield perfectly consistent, but rather odd, results.
- Function: set-mark POSITION
This function sets the mark to POSITION, and activates the mark.
The old value of the mark is *not* pushed onto the mark ring.
*Please note:* Use this function only if you want the user to see
that the mark has moved, and you want the previous mark position to
be lost. Normally, when a new mark is set, the old one should go
on the `mark-ring'. For this reason, most applications should use
`push-mark' and `pop-mark', not `set-mark'.
Novice Emacs Lisp programmers often try to use the mark for the
wrong purposes. The mark saves a location for the user's
convenience. An editing command should not alter the mark unless
altering the mark is part of the user-level functionality of the
command. (And, in that case, this effect should be documented.)
To remember a location for internal use in the Lisp program, store
it in a Lisp variable. For example:
(let ((beg (point)))
(forward-line 1)
(delete-region beg (point))).
- Function: push-mark &optional POSITION NOMSG ACTIVATE
This function sets the current buffer's mark to POSITION, and
pushes a copy of the previous mark onto `mark-ring'. If POSITION
is `nil', then the value of point is used. `push-mark' returns
`nil'.
The function `push-mark' normally *does not* activate the mark.
To do that, specify `t' for the argument ACTIVATE.
A `Mark set' message is displayed unless NOMSG is non-`nil'.
- Function: pop-mark
This function pops off the top element of `mark-ring' and makes
that mark become the buffer's actual mark. This does not move
point in the buffer, and it does nothing if `mark-ring' is empty.
It deactivates the mark.
The return value is not meaningful.
- User Option: transient-mark-mode
This variable if non-`nil' enables Transient Mark mode, in which
every buffer-modifying primitive sets `deactivate-mark'. The
consequence of this is that commands that modify the buffer
normally make the mark inactive.
- Variable: deactivate-mark
If an editor command sets this variable non-`nil', then the editor
command loop deactivates the mark after the command returns, but
only if Transient Mark mode is enabled.
- Function: deactivate-mark
This function deactivates the mark, but only if Transient Mark mode
is enabled.
- Variable: mark-active
The mark is active when this variable is non-`nil'. This variable
is always local in each buffer.
- Variable: activate-mark-hook
- Variable: deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes
active and when it becomes inactive. The hook
`activate-mark-hook' is also run at the end of a command if the
mark is active and the region may have changed.
- Variable: mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
mark-ring
=> (#<marker at 11050 in markers.texi>
#<marker at 10832 in markers.texi>
...)
- User Option: mark-ring-max
The value of this variable is the maximum size of `mark-ring'. If
more marks than this are pushed onto the `mark-ring', `push-mark'
discards an old mark when it adds a new one.
File: elisp, Node: The Region, Prev: The Mark, Up: Markers
The Region
==========
The text between point and the mark is known as "the region".
Various functions operate on text delimited by point and the mark, but
only those functions specifically related to the region itself are
described here.
- Function: region-beginning
This function returns the position of the beginning of the region
(as an integer). This is the position of either point or the mark,
whichever is smaller.
If the mark does not point anywhere, an error is signaled.
- Function: region-end
This function returns the position of the end of the region (as an
integer). This is the position of either point or the mark,
whichever is larger.
If the mark does not point anywhere, an error is signaled.
Few programs need to use the `region-beginning' and `region-end'
functions. A command designed to operate on a region should normally
use `interactive' with the `r' specification to find the beginning and
end of the region. This lets other Lisp programs specify the bounds
explicitly as arguments. (*Note Interactive Codes::.)
File: elisp, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
This chapter describes the functions that deal with the text in a
buffer. Most examine, insert, or delete text in the current buffer,
often in the vicinity of point. Many are interactive. All the
functions that change the text provide for undoing the changes (*note
Undo::.).
Many text-related functions operate on a region of text defined by
two buffer positions passed in arguments named START and END. These
arguments should be either markers (*note Markers::.) or numeric
character positions (*note Positions::.). The order of these arguments
does not matter; it is all right for START to be the end of the region
and END the beginning. For example, `(delete-region 1 10)' and
`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
signaled if either START or END is outside the accessible portion of
the buffer. In an interactive call, point and the mark are used for
these arguments.
Throughout this chapter, "text" refers to the characters in the
buffer, together with their properties (when relevant).
* Menu:
* Near Point:: Examining text in the vicinity of point.
* Buffer Contents:: Examining text in a general fashion.
* Comparing Text:: Comparing substrings of buffers.
* Insertion:: Adding new text to a buffer.
* Commands for Insertion:: User-level commands to insert text.
* Deletion:: Removing text from a buffer.
* User-Level Deletion:: User-level commands to delete text.
* The Kill Ring:: Where removed text sometimes is saved for later use.
* Undo:: Undoing changes to the text of a buffer.
* Maintaining Undo:: How to enable and disable undo information.
How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
* Columns:: Computing horizontal positions, and using them.
* Indentation:: Functions to insert or adjust indentation.
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Change Hooks:: Supplying functions to be run when text is changed.